.\"
.\" Copyright (C) 2012-2014 Carnegie Mellon University
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of version 2 of the GNU General Public License as published
.\" by the Free Software Foundation.  A copy of the GNU General Public License
.\" should have been distributed along with this program in the file
.\" COPYING.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.TH VMNETX-GENERATE 1 2014-09-18 "VMNetX @version@" "User Commands"

.SH NAME
vmnetx-generate \- Construct a new VMNetX virtual machine image

.SH SYNOPSIS
.B vmnetx-generate
.B create
.RB [ \-w ]
.I SHORT-NAME MEMORY-MB DISK-GB
.br
.B vmnetx-generate
.B validate
.I DOMAIN-XML
.br
.B vmnetx-generate
.B package
.RB [ \-n
.IR FRIENDLY-NAME ]
.RB [ \-u ]
.I DOMAIN-XML OUT-FILE
.br
.B vmnetx-generate
.B reference
.I PACKAGE-URL OUT-FILE

.SH DESCRIPTION
.B vmnetx-generate
creates and operates on virtual machines compatible with
.BR vmnetx (1).
.B vmnetx-generate
provides tools for adding new blank virtual machines to
.BR virt-manager (1),
validating libvirt domain XML, generating
.I .nxpk
virtual machine packages from
.BR virt-manager (1)
virtual machines, and creating
.I .netx
reference files linking to remote virtual machines.

.SS Packaging a Virtual Machine for VMNetX
To create a virtual machine package, begin by using
.B vmnetx-generate create
to add a new, empty VM to
.BR virt-manager (1).
Use
.BR virt-manager (1)
to install and configure the VM.

.PP
Once the VM is ready to be packaged, it should be shut down.
The VM's domain XML should be validated with
.B vmnetx-generate validate
and modified if necessary to ensure that it conforms to the requirements of
.BR vmnetx (1).
If the VM package should include a memory image, the VM should then be
started in
.BR virt-manager (1)
and subsequently suspended.

.PP
.B vmnetx-generate package
should be used to generate a VMNetX virtual machine package with a
.I .nxpk
extension.  This package file can be uploaded to a web server.

.PP
To enable users to execute the virtual machine without downloading the
entire package, create a link to the package using a
.I vmnetx+http:
or
.I vmnetx+https:
URL.
This will cause web browsers to open the link using
.BR vmnetx (1).
Alternatively, for compatibility with VMNetX versions earlier than 0.5.0,
you can create a
.I reference file
using
.BR vmnetx-generate\ reference .
This file should be uploaded to the web server with a
.I .netx
extension and an
.I application/x-vmnetx-reference+xml
content type, and a link to this
.I .netx
file should be published for access.

.SH MODES
vmnetx-generate has several modes of operation:

.TP
.BI create\ [-w] \ SHORT-NAME\ MEMORY-MB\ DISK-GB
Create a new, empty virtual machine with the specified name, memory size in
MB, and disk size in GB, and add it to
.BR virt-manager (1).

.TP
.BI validate\  DOMAIN-XML
Validate the specified domain XML file for a virtual machine to ensure that
it will be accepted by
.BR vmnetx (1).

.TP
.BI package\ [-n\  FRIENDLY-NAME ]\ [-u] \ DOMAIN-XML\ OUT-FILE
Validate the specified domain XML file for a virtual machine, then create a
VMNetX package containing the virtual machine's domain XML, virtual disk,
and optionally its memory image.

.TP
.BI reference\  PACKAGE-URL\ OUT-FILE
Create the reference file
.I OUT-FILE
linking to the remote VMNetX package at
.IR PACKAGE-URL .

.SH OPTIONS
.TP
.BR \-h ", " \-\^\-help
Print a usage message summarizing these options, then exit.
.TP
.BI \-n\fR, "" \ \-\-name\  FRIENDLY-NAME
The friendly name of the virtual machine, to be displayed in the
.BR vmnetx (1)
title bar.
.TP
.BR \-u ", " \-\-uncompressed
Create the package with uncompressed memory and disk images.
.TP
.B \-\^\-version
Print the version number of
.B vmnetx-generate
and exit.
.TP
.BR \-w ", " \-\-64\-bit
Enable 64-bit processor extensions.

.SH EXAMPLES

.TP
.B vmnetx-generate create dos622 1024 1
Create a new, empty virtual machine named
.I dos622
with 1024
MB of allocated RAM and 1 GB of allocated disk space, and add it to
.BR virt-manager (1).

.TP
.B vmnetx-generate validate ~/.config/libvirt/qemu/macos.xml
Check the specified domain XML for VMNetX compatibility.

.TP
.B vmnetx-generate package \-n \(dqWindows 3.1\(dq ~/.config/libvirt/qemu/windows311.xml windows311.nxpk
Create a VMNetX package file in the current directory.

.TP
.B vmnetx-generate reference http://example.com/package.nxpk package.netx
Create a reference file in the current directory linking to a package file
hosted on
.IR example.com .

.SH COPYRIGHT
Copyright 2006-2014 Carnegie Mellon University.
.PP
This program is free software; you can redistribute it and/or modify it
under the terms of version 2 of the GNU General Public License as published
by the Free Software Foundation. This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.
.
.SH BUGS
.BR vmnetx 's
bug tracker and source repository are located at
.RB < https://github.com/cmusatyalab/vmnetx >.

.SH SEE ALSO
.BR qemu (1),
.BR qemu-kvm (1),
.BR virt-manager (1),
.BR vmnetx (1),
.BR vmnetx-server (8)
.\" This is allegedly a workaround for some troff -man implementations.
.br
